KTOR-9165 and KTOR-9193 Documentation for OpenAPI specification generation #744

vnikolova · 2025-12-23T14:15:35Z

Add documentation for runtime route annotations
Update compiler plugin docs for new configuration options
add "what's new" sections
Add a sample project
Remove experimental label
update the Swagger UI and OpenAPI plugin topics

coderabbitai · 2025-12-23T14:15:41Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

…i compiler extension

codeSnippets/snippets/openapi-spec-gen/README.md

codeSnippets/snippets/openapi-spec-gen/build.gradle.kts

bjhham · 2026-01-12T09:53:43Z

codeSnippets/snippets/openapi-spec-gen/src/main/kotlin/com/example/Application.kt

+                }.annotate {
+                    summary = "Get users"
+                    description = "Retrieves a list of users."
+                    parameters {
+                        query("q") {
+                            description = "An encoded query"
+                            required = false
+                        }
+                    }
+                    responses {
+                        HttpStatusCode.OK {
+                            description = "A list of users"
+                            schema = jsonSchema<List<User>>()
+                        }
+                        HttpStatusCode.BadRequest {
+                            description = "Invalid query"
+                            ContentType.Text.Plain()
+                        }
+                    }
+                }


Would be good to leave a comment here that describes the order of precedence here in building the final model. In this case, we have the comment API and code inference that will supply some of the details, which will merged with the runtime API call from the annotate function.

Added a short paragraph below the example and a new section called "Metadata precedence". Not sure if the placement of it makes sense though and if it's better to place it higher up 🤔

bjhham · 2026-01-12T10:00:55Z

topics/openapi-spec-generation.md

+#### Supported KDoc fields
+
+| Tag             | Format                                          | Description                      |
+|-----------------|-------------------------------------------------|----------------------------------|
+| `@tag`          | `@tag *name`                                    | Groups the endpoint under a tag  |
+| `@path`         | `@path [Type] name description`                 | Path parameter                   |
+| `@query`        | `@query [Type] name description`                | Query parameter                  |
+| `@header`       | `@header [Type] name description`               | Header parameter                 |
+| `@cookie`       | `@cookie [Type] name description`               | Cookie parameter                 |
+| `@body`         | `@body contentType [Type] description`          | Request body                     |
+| `@response`     | `@response code contentType [Type] description` | Response definition              |
+| `@deprecated`   | `@deprecated reason`                            | Marks the endpoint as deprecated |
+| `@description`  | `@description text`                             | Extended description             |
+| `@security`     | `@security scheme`                              | Security requirements            |
+| `@externalDocs` | `@external href`                                | External documentation link      |


For 3.4.0, we're updating the comment API style from KDoc tags to use a custom markdown format, due to some concerns over the tags potentially causing some unexpected behaviour in the IDE and KDoc processing. I just changed this last week after some comments from @whyoleg, so it's pretty last-minute 😅

So now all these keywords instead just need to be at the start of the line with a colon divider to designate the value:

/** * Get a list of widgets. * * - Tags: * - widgets * - admin * - Cookie: X-Analytics-Session some tracking cookie * - Responses: * - 200 application/json [Widget]+ A list of widgets * - 400 Invalid request */

Note, the plural form with tags and responses is an optional format, you can also use Tag: widgets, and the list bullets at the top level are also optional and just a matter of preference for formatting.

Thanks for the tip. I've updated the section to reflect the changes.

bjhham · 2026-01-12T10:08:08Z

topics/openapi-spec-generation.md

+    val docs = generateOpenApiDoc(
+        OpenApiDoc(info = OpenApiInfo("My API", "1.0")),
+        apiRoute.descendants()
+    )
+    call.respond(docs)


Worth noting that docs is a io.ktor.openapi.OpenApiDoc and the return here is assuming you're using ContentNegotiation with kotlinx-serialization and JSON. Alternatively, you could just use Json.encodeToString(docs) with ContentType.Application.Json here with respondText so it's explicit in how it's serializing the model.

Added some clarification and a note with an alternative code sample using Json.encodeToString(docs) with ContentType.Application.Json.

bjhham · 2026-01-12T10:13:15Z

topics/openapi-spec-generation.md

+To expose the OpenAPI specification through an interactive UI, use the [OpenAPI](server-openapi.md)
+and [SwaggerUI](server-swagger-ui.md) plugins.


I'm not sure if we have good documentation for the difference between the two plugins. I don't really know the full extent of the differences, but from what I can tell the main difference is that the OpenAPI renders the HTML from the provided model on the back end, and SwaggerUI renders the details from the front end and exposes the model endpoint as JSON or YAML. I would say the Swagger plugin ought to be the default implementation since it's a more modern UI and it's easier to navigate. Maybe @e5l could have some thoughts on this.

Added a couple of bullet points to clarify the difference between the two and updated the plugin topics.

bjhham · 2026-01-12T10:16:39Z

topics/whats-new-340.md


+### Runtime route annotations
+
+Ktor 3.4.0 introduces the `ktor-server-routing-annotate` module, which allows you to attach OpenAPI metadata directly


I'm thinking of changing the name of this module before the release to ktor-server-openapi-annotate - I'd originally used routing because I was thinking of a more generic model and only providing the routing function in here, but since then it's become more OpenAPI-specific and provides the means for top-level information as well.

… rules

codeSnippets/build.gradle

topics/openapi-spec-generation.md

…id deps

danil-pavlov · 2026-01-15T16:01:09Z

topics/openapi-spec-generation.md

+    }
+}
 ```
+> For a complete list of available fields, refer to [the OpenAPI Specification](https://swagger.io/specification/#operation-object).


Suggested change

> For a complete list of available fields, refer to [the OpenAPI Specification](https://swagger.io/specification/#operation-object).

> For a complete list of available fields, refer to the [OpenAPI specification](https://swagger.io/specification/#operation-object).

>

{style="tip"}

danil-pavlov · 2026-01-15T16:01:56Z

topics/server-openapi.md

+Ktor allows you to serve OpenAPI documentation based on an OpenAPI specification.
+
+You can provide the OpenAPI specification in one of the following ways:
+- [Serve an existing YAML or JSON file](#static-openapi-file).


Suggested change

- [Serve an existing YAML or JSON file](#static-openapi-file).

* [Serve an existing YAML or JSON file](#static-openapi-file).

danil-pavlov · 2026-01-15T16:02:06Z

topics/server-openapi.md

+
+You can provide the OpenAPI specification in one of the following ways:
+- [Serve an existing YAML or JSON file](#static-openapi-file).
+- [Generate the specification at runtime using the OpenAPI compiler extension and runtime APIs](#generate-runtime-openapi-metadata).


Suggested change

- [Generate the specification at runtime using the OpenAPI compiler extension and runtime APIs](#generate-runtime-openapi-metadata).

* [Generate the specification at runtime using the OpenAPI compiler extension and runtime APIs](#generate-runtime-openapi-metadata).

danil-pavlov · 2026-01-15T16:03:22Z

topics/server-openapi.md

+With this, you can access the generated OpenAPI documentation at the `/openapi` path, reflecting the current state of the
+application.
+
+> For more information on the OpenAPI compiler extension and runtime APIs, see [](openapi-spec-generation.md).


Suggested change

> For more information on the OpenAPI compiler extension and runtime APIs, see [](openapi-spec-generation.md).

> For more information on the OpenAPI compiler extension and runtime APIs, see [](openapi-spec-generation.md).

>

{style="tip"}

danil-pavlov · 2026-01-15T16:03:48Z

topics/server-openapi.md

+
+## Configure OpenAPI {id="configure-openapi"}
+
+By default, documentation is rendered using `StaticHtml2Codegen`. You can customize the renderer inside the `openAPI() { }`


Suggested change

By default, documentation is rendered using `StaticHtml2Codegen`. You can customize the renderer inside the `openAPI() { }`

By default, documentation is rendered using `StaticHtml2Codegen`. You can customize the renderer inside the `openAPI {}`

danil-pavlov · 2026-01-15T16:27:06Z

topics/whats-new-340.md

+regular builds, and changes to routes or annotations are reflected in the running server without requiring any
+additional generation steps.
+
+


Suggested change

danil-pavlov · 2026-01-15T16:29:19Z

topics/whats-new-340.md


+Global OpenAPI metadata is now defined and resolved at runtime rather than during compilation.
+
+The compiler extension configuration is now limited to feature flags that control how metadata is inferred and collected.


Suggested change

The compiler extension configuration is now limited to feature flags that control how metadata is inferred and collected.

The compiler extension configuration is now limited to feature options that control how metadata is inferred and collected.

danil-pavlov · 2026-01-15T16:30:47Z

topics/whats-new-340.md

+#### Configuration

+Configuration is still done using the `openApi {}` block inside the `ktor` Gradle extension. However, properties used
+to define global OpenAPI metadata such as `title`, `version`, `description`, and `target` have been deprecated and are


Suggested change

to define global OpenAPI metadata such as `title`, `version`, `description`, and `target` have been deprecated and are

to define global OpenAPI metadata, such as `title`, `version`, `description`, and `target`, have been deprecated and are

danil-pavlov · 2026-01-15T16:32:09Z

topics/whats-new-340.md

+}
+```
+
+This API can be used as a standalone extension or in conjunction with Ktor's OpenAPI compiler plugin for the automatic


Suggested change

This API can be used as a standalone extension or in conjunction with Ktor's OpenAPI compiler plugin for the automatic

You can use this API as a standalone extension or in combination with Ktor's OpenAPI compiler plugin to automatically

danil-pavlov · 2026-01-15T16:32:26Z

topics/whats-new-340.md

+```
+
+This API can be used as a standalone extension or in conjunction with Ktor's OpenAPI compiler plugin for the automatic
+generation of these calls. The [OpenAPI](server-openapi.md) and


Suggested change

generation of these calls. The [OpenAPI](server-openapi.md) and

generate these calls. The [OpenAPI](server-openapi.md) and

danil-pavlov · 2026-01-16T17:14:20Z

topics/openapi-spec-generation.md

+Ktor provides support for building OpenAPI specifications at runtime from one or more documentation sources.
+
+This functionality is available through:
+- The OpenAPI compiler extension (included in the Ktor Gradle plugin), which analyzes routing code at compile time and


Suggested change

- The OpenAPI compiler extension (included in the Ktor Gradle plugin), which analyzes routing code at compile time and

* The OpenAPI compiler extension (included in the Ktor Gradle plugin), which analyzes routing code at compile time and

danil-pavlov · 2026-01-16T17:14:32Z

topics/openapi-spec-generation.md

+This functionality is available through:
+- The OpenAPI compiler extension (included in the Ktor Gradle plugin), which analyzes routing code at compile time and
+generates Kotlin code that registers OpenAPI metadata at runtime.
+- The routing annotation runtime API, which attaches OpenAPI metadata directly to routes in the running application.


Suggested change

- The routing annotation runtime API, which attaches OpenAPI metadata directly to routes in the running application.

* The routing annotation runtime API, which attaches OpenAPI metadata directly to routes in the running application.

danil-pavlov · 2026-01-16T17:14:44Z

topics/openapi-spec-generation.md

+generates Kotlin code that registers OpenAPI metadata at runtime.
+- The routing annotation runtime API, which attaches OpenAPI metadata directly to routes in the running application.
+
+You can use one, or both, and combine them with the [OpenAPI](server-openapi.md)


Suggested change

You can use one, or both, and combine them with the [OpenAPI](server-openapi.md)

You can use one or both and combine them with the [OpenAPI](server-openapi.md)

danil-pavlov · 2026-01-16T17:15:26Z

topics/openapi-spec-generation.md

 ```

-## Configure the extension
+* To use runtime route annotations, add the `%artifact_name%` artifact in your build script:


Suggested change

* To use runtime route annotations, add the `%artifact_name%` artifact in your build script:

* To use runtime route annotations, add the `%artifact_name%` artifact to your build script:

danil-pavlov · 2026-01-16T17:25:22Z

topics/openapi-spec-generation.md

+
+## Generate and serve the specification
+
+The OpenAPI specification is assembled at runtime using metadata generated by the compiler plugin together with runtime


It reads a bit confusing, is "together with annotations" refers to the compiler plugin or specification?
maybe put it in a different order:

The OpenAPI specification is assembled at runtime from runtime route annotations and metadata generated by the compiler plugin.

danil-pavlov · 2026-01-16T17:43:42Z

topics/openapi-spec-generation.md

-| `@externalDocs` | `@external href`                                | External documentation links                    |
+### Runtime route annotations {id="runtime-route-annotations"}

+In cases where compile-time analysis is insufficient — such as when using dynamic routing, interceptors, or conditional


Suggested change

In cases where compile-time analysis is insufficient — such as when using dynamic routing, interceptors, or conditional

In cases where compile-time analysis is insufficient, such as when using dynamic routing, interceptors, or conditional

danil-pavlov · 2026-01-16T17:43:54Z

topics/openapi-spec-generation.md

+The metadata is attached to the routing tree at runtime and is consumed by the OpenAPI and Swagger UI plugins.

-To generate the OpenAPI specification, run the following Gradle task:
+The `.annotate { }` DSL maps directly to the OpenAPI Specification. Property names and structure correspond to the


Suggested change

The `.annotate { }` DSL maps directly to the OpenAPI Specification. Property names and structure correspond to the

The `.annotate {}` DSL maps directly to the OpenAPI specification. Property names and structure correspond to the

danil-pavlov · 2026-01-16T17:47:50Z

topics/openapi-spec-generation.md

+>   ContentType.Application.Json
+> )
+>```
+


Suggested change

>

{style="note"}

danil-pavlov · 2026-01-16T17:48:19Z

topics/openapi-spec-generation.md

+This assumes that a JSON serializer (for example, `kotlinx.serialization`) is installed.
+
+> If you want to make serialization explicit or avoid relying on `ContentNegotiation`, you can encode the document
+> manually and respond with JSON:


Suggested change

> manually and respond with JSON:

> manually and respond with a JSON:

>

danil-pavlov · 2026-01-16T17:57:23Z

topics/openapi-spec-generation.md

@@ -1,66 +1,106 @@
 [//]: # (title: OpenAPI specification generation)


Comment for the whole page: there's now a mix of imperative headers like "Configure..", "Annotate..", "Generate and serve.." and noun phrases like "Code inference", "Metadate precedence" on the second header level. Perhaps you can rephrase them or move to a lower level. For example, "Enable code inference" or move "Metadata precedence" inside "Generate and serve.." since it's also about assembling the final specification

vnikolova added 2 commits January 7, 2026 11:57

KTOR-9165 and KTOR-9193 docs for runtime route annotations and openap…

c3623a8

…i compiler extension

add a code sample project, update docs and add todos

ef10e78

vnikolova force-pushed the vnikolova/openapi-spec-gen branch from 3c9da2d to ef10e78 Compare January 7, 2026 10:58

vnikolova added 2 commits January 7, 2026 17:21

update openapi compiler plugin configuration

61898e8

update for technical accuracy and add links

a189f03

vnikolova marked this pull request as ready for review January 9, 2026 13:13

vnikolova changed the title ~~WIP: Documentation for OpenAPI specification generation~~ KTOR-9165 and KTOR-9193 Documentation for OpenAPI specification generation Jan 9, 2026

vnikolova requested a review from bjhham January 9, 2026 13:14

bjhham reviewed Jan 12, 2026

View reviewed changes

update comment formatting, add metadata precedence and code inference…

2422d37

… rules

bjhham reviewed Jan 12, 2026

View reviewed changes

codeSnippets/build.gradle Show resolved Hide resolved

topics/openapi-spec-generation.md Outdated Show resolved Hide resolved

update sample project, compiler config options descriptions and inval…

78a1528

…id deps

vnikolova force-pushed the vnikolova/openapi-spec-gen branch from c3130ed to 78a1528 Compare January 13, 2026 16:15

update the swagger and openapi plugin topics

320c30d

vnikolova force-pushed the vnikolova/openapi-spec-gen branch from 397e4a9 to 320c30d Compare January 14, 2026 10:37

vnikolova requested a review from nomisRev January 14, 2026 10:41

danil-pavlov self-requested a review January 15, 2026 15:31

danil-pavlov requested changes Jan 16, 2026

View reviewed changes

		To expose the OpenAPI specification through an interactive UI, use the [OpenAPI](server-openapi.md)
		and [SwaggerUI](server-swagger-ui.md) plugins.


		### Runtime route annotations

		Ktor 3.4.0 introduces the `ktor-server-routing-annotate` module, which allows you to attach OpenAPI metadata directly

-> For a complete list of available fields, refer to [the OpenAPI Specification](https://swagger.io/specification/#operation-object).
+> For a complete list of available fields, refer to the [OpenAPI specification](https://swagger.io/specification/#operation-object).
+>
+{style="tip"}

	- [Serve an existing YAML or JSON file](#static-openapi-file).

	* [Serve an existing YAML or JSON file](#static-openapi-file).

	- [Generate the specification at runtime using the OpenAPI compiler extension and runtime APIs](#generate-runtime-openapi-metadata).
	* [Generate the specification at runtime using the OpenAPI compiler extension and runtime APIs](#generate-runtime-openapi-metadata).


		## Configure OpenAPI {id="configure-openapi"}

		By default, documentation is rendered using `StaticHtml2Codegen`. You can customize the renderer inside the `openAPI() { }`

		regular builds, and changes to routes or annotations are reflected in the running server without requiring any
		additional generation steps.


		Global OpenAPI metadata is now defined and resolved at runtime rather than during compilation.

		The compiler extension configuration is now limited to feature flags that control how metadata is inferred and collected.

	to define global OpenAPI metadata such as `title`, `version`, `description`, and `target` have been deprecated and are
	to define global OpenAPI metadata, such as `title`, `version`, `description`, and `target`, have been deprecated and are

	This API can be used as a standalone extension or in conjunction with Ktor's OpenAPI compiler plugin for the automatic
	You can use this API as a standalone extension or in combination with Ktor's OpenAPI compiler plugin to automatically

	generation of these calls. The [OpenAPI](server-openapi.md) and
	generate these calls. The [OpenAPI](server-openapi.md) and

	- The OpenAPI compiler extension (included in the Ktor Gradle plugin), which analyzes routing code at compile time and

	* The OpenAPI compiler extension (included in the Ktor Gradle plugin), which analyzes routing code at compile time and

	- The routing annotation runtime API, which attaches OpenAPI metadata directly to routes in the running application.
	* The routing annotation runtime API, which attaches OpenAPI metadata directly to routes in the running application.

	You can use one, or both, and combine them with the [OpenAPI](server-openapi.md)
	You can use one or both and combine them with the [OpenAPI](server-openapi.md)

	* To use runtime route annotations, add the `%artifact_name%` artifact in your build script:
	* To use runtime route annotations, add the `%artifact_name%` artifact to your build script:


		## Generate and serve the specification

		The OpenAPI specification is assembled at runtime using metadata generated by the compiler plugin together with runtime

	In cases where compile-time analysis is insufficient — such as when using dynamic routing, interceptors, or conditional
	In cases where compile-time analysis is insufficient, such as when using dynamic routing, interceptors, or conditional

	The `.annotate { }` DSL maps directly to the OpenAPI Specification. Property names and structure correspond to the
	The `.annotate {}` DSL maps directly to the OpenAPI specification. Property names and structure correspond to the

	> manually and respond with JSON:
	> manually and respond with a JSON:
	>

		@@ -1,66 +1,106 @@
		[//]: # (title: OpenAPI specification generation)

KTOR-9165 and KTOR-9193 Documentation for OpenAPI specification generation #744

Are you sure you want to change the base?

KTOR-9165 and KTOR-9193 Documentation for OpenAPI specification generation #744

Uh oh!

Conversation

vnikolova commented Dec 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot commented Dec 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

danil-pavlov Jan 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

vnikolova commented Dec 23, 2025 •

edited

Loading

coderabbitai bot commented Dec 23, 2025 •

edited

Loading

danil-pavlov Jan 15, 2026 •

edited

Loading